/*
 * ----------------------------------------------------------------------------
 *  (C) Copyright European Telecommunications Standards Institute, 2001.
 *  All Rights Reserved.
 *
 *  All copies of this program, whether in whole or in part, and whether
 *  modified or not, must display this and all other embedded copyright
 *  and ownership notices in full.
 *
 * ----------------------------------------------------------------------------
 */
package org.etsi.ttcn.tri;

import java.io.Serializable;

/**  
     <p>This interface includes all operations necessary to adapt the
     TTCN-3 Executable to a particular execution platform. The
     triPlatform interface offers means to start, stop, read a timer,
     enquire its status and to add timeout events to the expored timer
     list. In addition, it offers operations to call TTCN-3 external
     functions and to reset the Platform Adapter. Notice that there is
     not differentiation between explicit and implicit timers required
     at the triPlatform interface. Instead each timer shall be
     addressed uniformly with its timer identifier.
*/

public interface TriPlatformPA extends Serializable {

    /** 
	<p>This operation can be called by the TE at any time to reset
	the PA.

	<p>The PA shall reset all timing activities which it is
	currently performing, e.g., stop all running timers, discard
	any pending timeouts of expired timers.  The triResetSA
	operation returns TRI_OK in case the operation has been
	performed successfully, TRI_Error otherwise.

	@return The return status of the triPAReset operation. The
	return status indicates the local success (TRI_OK) or failure
	(TRI_Error) of the operation.

	@see "TRI-Definition 7.6.1"
    */
    public TriStatus triPAReset();

    /** 
	<p>This operation is called by the TE when a timer needs to be
	started.

	<p>On invocation of this operation the PA shall start the
	indicated timer with the indicated duration. The timer runs
	from the value zero (0.0) up to the maximum specified by
	timerDuration. Should the timer indicated by timerId already
	be running it is to be restarted. When the timer expires the
	PA will call the triTimeout() operation with timerId.  The
	triStartTimer operation returns TRI_OK if the timer has been
	started successfully, TRI_Error otherwise.

	@param	timerId	identifier of the timer instance

	@param	timerDuration	duration of the timer in seconds

	@return Return Value The return status of the triStartTimer
	operation. The return status indicates the local success
	(TRI_OK) or failure (TRI_Error) of the operation.

	@see "TRI-Definition 7.6.2"
    */
    public TriStatus triStartTimer(TriTimerId timerId, 
	TriTimerDuration timerDuration);

    /** 
	<p>This operation is called by the TE when a timer is to be
	stopped.

	<p>On invocation of this operation the PA shall use the
	timerId to stop the indicated timer instance. The stopping of
	an inactive timer, i.e., a timer which has not been started or
	has already expired, should have no effect.  The triStopTimer
	operation returns TRI_OK if the operation has been performed
	successfully, TRI_Error otherwise. Notice that stopping an
	inactive timer is a valid operation. In this case TRI_OK shall
	be returned.

	@param	timerId	identifier of the timer instance

	@return The return status of the triStopTimer operation. The
	return status indicates the local success (TRI_OK) or failure
	(TRI_Error) of the operation.

	@see  "TRI-Definition 7.6.3"

    */
    public TriStatus triStopTimer(TriTimerId timerId);
    
    /** 
	<p>This operation may be called by the TE when a TTCN-3 read
	timer operation is to be executed on the indicated timer (see
	Section 7.1.3).
	
	<p>On invocation of this operation the PA shall use the
	timerId to access the time that elapsed since this timer was
	started. The return value elapsedTime shall be provided in
	seconds. The reading of an inactive timer, i.e., a timer which
	has not been started or already expired, shall return an
	elapsed time value of zero.  The triReadTimer operation
	returns TRI_OK if the operation has been performed
	successfully, TRI_Error otherwise.

	@param	timerId	identifier of  the timer instance

	@param elapsedTime value of the time elapsed since the timer
	has been started in seconds

	@return The return status of the triReadTimer operation. The
	return status indicates the local success (TRI_OK) or failure
	(TRI_Error) of the operation.
	
	@see "TRI-Definition 7.6.4"
    */
    public TriStatus triReadTimer(TriTimerId timerId, 
	TriTimerDuration elapsedTime);
    
    /** 
	<p>This operation may be called by the TE when a TTCN-3
	running timer operation is to be executed on the indicated
	timer (see Section 7.1.3).

	<p>On invocation of this operation the PA shall use the
	timerId to access the status of the timer. The operation sets
	running to the boolean value true if and only if the timer is
	currently running.  The triTimerRunning operation returns
	TRI_OK if the status of the timer has been successfully
	determined, TRI_Error otherwise

	@param timerId identifier of the timer instance

	@param running status of the timer

	@return The return status of the triTimerRunning
	operation. The return status indicates the local success
	(TRI_OK) or failure (TRI_Error) of the operation.

	@see "TRI-Definition 7.6.5"
    */
    public TriStatus triTimerRunning(TriTimerId timerId, 
	TriBoolean running);
    
    /**   
	  <p>This operation is called by the TE when it executes a
	  function which is defined to be TTCN-3 external (i.e., all
	  non-external functions are implemented within the TE).  In
	  the invocation of a triExternalFunction operation by the TE
	  all in and inout function parameters contain encoded
	  values. All out function parameters shall contain the
	  distinct value of null since they are only of relevance in
	  the return from the external function but not in its
	  invocation. No error shall be indicated by the PA in case
	  the value of any out parameter is non-null.

	  <p>For each external function specified in the TTCN-3 ATS
	  the PA shall implement the behavior. On invocation of this
	  operation the PA shall invoke the function indicated by the
	  identifier functionId. It shall access the specified in and
	  inout function parameters in parameterList, evaluate the
	  external function using the values of these parameters, and
	  compute values for inout and out parameters in
	  parameterList. The operation shall then return encoded
	  values for all inout and out function parameters, the
	  distinct value of null for all in parameters, and the
	  encoded return value of the external function.  If no return
	  type has been defined for this external function in the
	  TTCN-3 ATS, the distinct value null shall be used for the
	  latter.  The triExternalFunction operation returns TRI_OK if
	  the PA completes the evaluation of the external function
	  successfully, TRI_Error otherwise.  Note that whereas all
	  other TRI operations are considered to be non-blocking, the
	  triExternalFunction operation is considered to be
	  blocking. That means that the operation shall not return
	  before the indicated external function has been fully
	  evaluated. External functions have to be implemented
	  carefully as they could cause deadlock of test component
	  execution or even the entire test system implementation.

	  @param functionId identifier of the external function
	
	  @param parameterList a list of encoded parameters for the
	  indicated function. The parameters in parameterList are
	  ordered as they appear in the TTCN-3 function declaration.

	  @param returnValue (optional) encoded return value

	  @return The return status of the triExternalFunction
	  operation. The return status indicates the local success
	  (TRI_OK) or failure (TRI_Error) of the operation.

	  @see "TRI-Definition 7.6.7"

    */		
    public TriStatus triExternalFunction(TriFunctionId functionId, 
	TriParameterList parameterList, TriParameter returnValue);
}
